.\" SPDX-License-Identifier: BSD-2-Clause
.\" Copyright (C) 2014 - 2021 Intel Corporation.
.\"
.TH "MEMKIND_HBW" 3 "2016-06-13" "Intel Corporation" "MEMKIND_HBW" \" -*- nroff -*-
.SH "NAME"
memkind_hbw \- high bandwidth memory memkind operations.
.br
.BR Note:
This is EXPERIMENTAL API. The functionality and the header file itself can be changed (including non-backward compatible changes) or removed.
.SH "SYNOPSIS"
.nf
.sp
.BI "int memkind_hbw_check_available(struct memkind " "*kind" );
.br
.BI "int memkind_hbw_hugetlb_check_available(struct memkind " "*kind" );
.br
.BI "int memkind_hbw_get_mbind_nodemask(struct memkind " "*kind" ", unsigned long " "*nodemask" ", unsigned long " "maxnode" );
.br
.BI "int memkind_hbw_get_preferred_mbind_nodemask(struct memkind " "*kind" ", unsigned long " "*nodemask" ", unsigned long " "maxnode" );
.br
.BI "int memkind_hbw_all_get_mbind_nodemask(struct memkind " "*kind" ", unsigned long " "*nodemask" ", unsigned long " "maxnode" );
.br
.BI "void memkind_hbw_init_once(void);"
.br
.BI "void memkind_hbw_hugetlb_init_once(void);"
.br
.BI "void memkind_hbw_all_hugetlb_init_once(void);"
.br
.BI "void memkind_hbw_preferred_init_once(void);"
.br
.BI "void memkind_hbw_preferred_hugetlb_init_once(void);"
.br
.BI "void memkind_hbw_interleave_init_once(void);"
.br
.SH DESCRIPTION
.PP
High bandwidth memory memkind operations.
.PP
.BR memkind_hbw_check_available ()
returns zero if library was able to detect heterogeneous NUMA node
bandwidths.   Returns
.B MEMKIND_ERROR_UNAVAILABLE
if the detection mechanism failed.
Detection mechanism can be also overridden by the
environment variable
.B MEMKIND_HBW_NODES
as described in the
.BR memkind (3)
man page.
.PP
.BR memkind_hbw_hugetlb_check_available ()
In addition to checking for high bandwidth memory as is done by
.BR memkind_hbw_check_available (),
this also checks for 2MB huge pages as
is done by
.BR memkind_hugetlb_check_available_2mb ().
.PP
.BR memkind_hbw_get_mbind_nodemask ()
sets the
.I nodemask
bit to one that corresponds to the high bandwidth NUMA nodes that has
the closest NUMA distance to the CPU of the calling process.
All other bits up to
.I maxnode
are set to zero.
The
.I nodemask
can be used in conjunction with the
.BR mbind (2)
system call.
.PP
.BR Note:
The function will fail if two or more
high bandwidth memory NUMA nodes are in the same the closest NUMA distance to the CPU of the calling process.
.BR memkind_hbw_get_preferred_mbind_nodemask ()
sets the
.I nodemask
bit to one that corresponds to the high bandwidth NUMA node that has
the closest NUMA distance to the CPU of the calling process.
All other bits up to
.I maxnode
are set to zero.
The
.I nodemask
can be used in conjunction with the
.BR mbind (2)
system call.
.PP
.BR memkind_hbw_all_get_mbind_nodemask ()
sets the
.I nodemask
bits to one that correspond to the all high bandwidth NUMA nodes in
the system. All other bits up to
.I maxnode
are set to zero.
The
.I nodemask
can be used in conjunction with the
.BR mbind (2)
system call.
.PP
.BR memkind_hbw_init_once ()
This function initializes
.B MEMKIND_HBW
kind and it should not be called more than once.
.BR Note:
.BR memkind_hbw_init_once ()
may reserve some extra memory.
.PP
.BR memkind_hbw_hugetlb_init_once ()
This function initializes
.B MEMKIND_HBW_HUGETLB
kind and it should not be called more than once.
.BR Note:
.BR memkind_hbw_hugetlb_init_once ()
may reserve some extra memory.
.PP
.BR memkind_hbw_preferred_init_once ()
This function initializes
.B MEMKIND_HBW_PREFERRED
kind and it should not be called more than once.
.BR Note:
.BR memkind_hbw_preferred_init_once ()
may reserve some extra memory.
.PP
.BR memkind_hbw_preferred_hugetlb_init_once ()
This function initializes
.B MEMKIND_HBW_PREFERRED_HUGETLB
kind and it should not be called more than once.
.BR Note:
.BR memkind_hbw_preferred_hugetlb_init_once ()
may reserve some extra memory.
.PP
.BR memkind_hbw_all_hugetlb_init_once ()
This function initializes
.B MEMKIND_HBW_ALL_HUGETLB
kind and it should not be called more than once.
.BR Note:
.BR memkind_hbw_all_hugetlb_init_once ()
may reserve some extra memory.
.PP
.BR memkind_hbw_interleave_init_once ()
This function initializes
.B MEMKIND_HBW_INTERLEAVE
kind and it should not be called more than once.
.BR Note:
.BR memkind_hbw_interleave_init_once ()
may reserve some extra memory.
.SH "COPYRIGHT"
Copyright (C) 2014 - 2021 Intel Corporation. All rights reserved.
.SH "SEE ALSO"
.BR memkind (3),
.BR memkind_arena (3),
.BR memkind_default (3),
.BR memkind_hugetlb (3),
.BR memkind_pmem (3),
.BR jemalloc (3),
.BR mbind (2),
.BR mmap (2)
